Amiga Collections: MegaDisc/MegaDisc 32 (1993-02)(MegaDisc Digital Publishing)(AU)(Disk 2 of 2).zip/MegaDisc 32 (1993-02)(MegaDisc Digital Publishing)(AU)(Disk 2 of 2).adf/hyperbook/HML_List

Text File | 1993-02-11 | 23KB | 710 lines

HyperBook control
numpages
 num = NUMPAGES ()
 Return the number of pages in the current hyperbook.

hyperbookname
 name = HYPERBOOKNAME ()
  Return the name (i.e. the full path name) of the current hyperbook.

loadhyperbook
 bool (0 or 1) = LOADHYPERBOOK (filename)
 Load the specified hyperbook.

savehyperbook
 bool (0 or 1) = SAVEHYPERBOOK (filename)
 Save the current hyperbook under the given name.

hyperbooktofront
 HYPERBOOKTOFRONT ()
 Bring the HyperBook screen to the front.

hyperbooktoback
 HYPERBOOKTOBACK ()
 Push the HyperBook screen to the back.

quithyperbook
 QUITHYPERBOOK ()
 Exit the HyperBook program.

Navigation
nextpage
 NEXTPAGE ()
 Equivalent to the right arrow gadget on the main control panel.

prevpage
 PREVPAGE ()
 Equivalent to the left arrow gadget on the main control panel.

gotopage
 old = GOTOPAGE (new)
 Go to the page whose objnum is new; return the objnum of the departed page.

callpage
 old = CALLPAGE (new)
 Go to the given new page, and return the objnum of the departed page. A
 subsequent RETURN will go back to the departed page.

return
 newpage = RETURN ()
 Make current the last page called (from Table of Contents, CALLPAGE, etc.),
 and return the objnum of that page.

Main control panel
bigpanel
 BIGPANEL ()
 Put the main control panel into its `big' state.

tinypanel
 TINYPANEL ()
 Put the main control panel into its `tiny' state.

controlpanel
 CONTROLPANEL (bool)
 Close (arg = 0) or open (arg = 1) the main control panel.

General editing
delete
 DELETE (arg)
 Delete a page, object or item, or empty the bin.

relocate
 new = RELOCATE (arg, newparent)
 Move the given object to the bin, a page or a group; or the given item to a
 new list. Return the new objnum of the object or item moved.

getbackground
 color = GETBACKGROUND (arg)
 Return the background color number of a page or object (-1 is returned for
 transparent object backgrounds).

setbackground
 oldcolor = SETBACKGROUND (arg, newcolor)
 Set the background color of a page or object, and return the old color. The
 object transparent `color' is -1.

getwidth
 width = GETWIDTH (arg)
 Return the width in pixels of the given page or object.

getheight
 width = GETHEIGHT (arg)
 Return the height in scan-lines of the given page or object.

getname
 name = GETNAME (arg)
 Return the name of a page or object.

setname
 oldname = SETNAME (arg, newname)
 Set the name of the given page or object, and return the previous name.

Page Creation
createpage
 page = CREATEPAGE (frompage, number)
 Create a new page with the given page number using the page specified by the
 frompage objnum as a template. The new page is a clone of frompage but does
 not have any objects on it. Giving zero as the page number causes the new
 page to be appended to the hyperbook. Return the objnum of the new page.

clonepage
 page = CLONEPAGE (frompage, number)
 Create a new page with the given page number using the page specified by the
 frompage objnum as a template. The new page is a clone of frompage,
 including any objects on it. Giving zero as the page number causes the new
 page to be appended to the hyperbook. Return the objnum of the new page.

mastertopage
 page = MASTERTOPAGE(name, pos)
 A new page is created at position pos from the given master page. The objnum
 of the new page is returned.

Master pages
pagetomaster
 PAGETOMASTER (page, name)
 Clone the specified page, including any objects on it, and add it to the
 master page list under the given name.

ismasterpage
 bool = ISMASTERPAGE (name)
 Return TRUE (1) if the given name is that of an existing master page.

deletemaster
 DELETEMASTER (name)
 Delete the master page of the given name.

Page files
loadpage
 page = LOADPAGE (file, num)
 Load the specified file as page num, and return the objnum of the
 newly-loaded page. A page number of 0 loads to the last page.

mergepage
 MERGEPAGE (parg, file)
 Merge the objects in the specified page file onto the page whose objnum is
 parg.

savepage
 SAVEPAGE (parg, file)
 Save the specified page to the named file.

Page editing
getpagelace
 bool (1 or 0) = GETPAGELACE (page)
 Returns 1 if the given page is in interlace mode, otherwise 0.

setpagelace
 bool (1 or 0) = SETPAGELACE (page, bool)
 Set the current page to interlace on (bool argument 1) or off (bool argument
 0). Return the previous interlace state.

getpagecolors
 count = GETPAGECOLORS (page)
 Return the number of colors in the palette of the given page.

setpagecolors
 oldcount = SETPAGECOLORS (arg, count)
 Set the number of colors (normalized to 4, 8 or 16) for the current page's
 palette, and return the old count.

getpagergb
 rgb = GETPAGERGB (page, reg)
 Return the packed rgb value of color register reg on the given page.

setpagergb
 oldrgb = SETPAGERGB (page, reg, rgb)
 Set the color register reg on the given page to the new rgb value, and
 return the old value of that register.

wiperoutine
 old = WIPEROUTINE (page, new)
 Get/set the wipe effect used by the given page. Values for new in the range
 0 to 17 will change the page effect as per the list at right; other values
 (e.g. -1) do not select a new effect.

pagedim
 old = PAGEDIM (page, new)
 Get/set the screen dimming effect that precedes the wipe effect for the
 given page, and return the previous setting. A new value of 0 turns dimming
 off; 1 turns it on. Other values (e.g. -1) do not change the current
 setting.

setpagenumber
 new = SETPAGENUMBER (page, num)
 Resequence the page whose position is num, and return its new objnum.

refreshpage
 REFRESHPAGE ()
 Redraw the current page.

Object creation
createnote
 note = CREATENOTE ()
 Create an empty note of size 61x23 and position (0,0) in the bin, using the
 current default note attributes, and return its objnum.

createbutton
 button = CREATEBUTTON ()
 Create an empty button of size 33x17 and position (0,0) in the bin, using
 the current default button attributes, and return its objnum.

createlist
 list = CREATELIST ()
 Create an empty list of size 65x43 and position (0,0) in the bin, using the
 current default list attributes, and return its objnum.

creategroup
 group = CREATEGROUP ()
 Create an empty group object in the bin, and return its objnum.

clone
 new = CLONE (arg, newparent)
 Clone the given object to the bin, a page or a group; or the given item to a
 new list. Arg is unchanged. Return the clone's objnum.

Object editing
getleft
 left = GETLEFT (obj)
 Return the left edge position of the object, measured in pixels from the
 left edge of its page.

gettop
 top = GETTOP (obj)
 Return the top edge position of the object, measured in scan-lines from the
 top edge of its page.

setposition
 SETPOSITION (obj, x, y)
 Set the left and top co-ordinates of the given object.

getborder
 border = GETBORDER (obj)
 Return the border color of the object, or -1 if the object's border is
 transparent.

setborder
 oldcolor = SETBORDER (obj, color)
 Set the border of the object to the given color, and return the previous
 color. The transparent `color' is -1.

getshadow
 shadow = GETSHADOW (obj)
 Return the shadow color of the object, or -1 if the object's shadow is
 transparent.

setshadow
 oldcolor = SETSHADOW (obj, color)
 Set the shadow of the object to the given color, and return the previous
 color. The transparent `color' is -1.

shadowstyle
 old = SHADOWSTYLE (obj, style)
 Get/set the style of shadow used by obj. The available styles are
 drop-shadow (style = 1) and embossed (2). Any other value (e.g. 0) doesn't
 change the current shadow style setting.

getvisibility
 bool (1 or 0) = GETVISIBILITY (obj)
 Return 1 if the `natural visibility state' of the object is visible, or 0 if
 it is invisible.

setvisibility
 bool (1 or 0) = SETVISIBILITY (obj, state)
 Set the `natural visibility state' of the object to visible (1), or
 invisible (0). Return the previous state.

scale
 SCALE (obj, percent)
 Scale the object's width and height to the given percentage of its current
 dimensions.

scaletosize
 SCALETOSIZE (obj, width, height)
 Scale the object to the given width and height.

objecttoback
 objnum = OBJECTTOBACK (obj)
 Bring the given object to the back of its group/page and return its new
 objnum.

objecttofront
 objnum = OBJECTTOFRONT (obj)
 Bring the given object to the front of its group/page and return its new
 objnum.

getgroupdepth
 depth = GETGROUPDEPTH (obj)
 Return the grouping depth of the given object, starting with 0 if the object
 is not in a group.

explode
 firstobj = EXPLODE (group)
 Explode the given group, and insert its constituent objects in the group's
 place in its parent list. Return the objnum of the first of these objects
 (or the empty string if the group had no objects).

Actions
getaction
 action = GETACTION (arg)
 Return the action type associated with the given object or item, one of:
 noaction, gopage, showpic, showhide, displaytext, doscommand, rexxcommand or
 rexxmacro.

getactiontext
 action = GETACTIONTEXT (arg)
 Return the text associated with the given object or item's action.

setactionnone
 oldact = SETACTIONNONE (arg)
 Set the action of the specified object or item to noaction. Return the type
 of the former action.

setactionpage
 oldact = SETACTIONPAGE (arg, parg)
 Set the action of the specified object or item to gopage. The page's objnum
 is parg. Return the type of the former action.

setactionpic
 oldact = SETACTIONPIC (arg, name)
 Set the action of the specified object or item to showpic. The picture is
 the ILBM file name. Return the type of the former action.

setactionshow
 oldact = SETACTIONSHOW (arg, oarg)
 Set the action of the specified object or item to showhide. The objnum of
 the target object is oarg. Return the type of the former action.

setactionread
 oldact = SETACTIONREAD (arg, name)
 Set the action of the specified object or item to displaytext. The text is
 in the file name. Return the type of the former action.

setactiondos
 oldact = SETACTIONDOS (arg, cmd)
 Set the action of the specified object or item to doscommand. The command is
 the string cmd. Return the type of the former action.

setactionrexx
 oldact = SETACTIONREXX (arg, dos)
 Set the action of the specified object or item to rexxcommand. The command
 is the string cmd. Return the type of the former action.

setactionmacro
 oldact = SETACTIONMACRO (arg, marg)
 Set the action of the specified object or item to rexxmacro. The named macro
 (marg) is used. Return the type of the former action.

setactionlink
 oldact = SETACTIONLINK (arg, linktype)
 Set the action of the specified object or item to one of the special
 variants of the gopage action: nextpage, prevpage, firstpage, lastpage,
 return or selectpage. Return the type of the former action.

activate
 ACTIVATE (object)
 Execute the action for the given object or item as though it had been
 clicked on.

Note and button text
readnotetext
 str = READNOTETEXT (arg, pos, amt)
 Return a string consisting of amt characters beginning at pos in the given
 note or button. An amt of -1 means `to the end of text'.

inserttext
 INSERTTEXT (arg, text, pos)
 Insert text at pos in the given note or button. If pos is -1, the text is
 appended.

replacetext
 oldtext = REPLACETEXT (arg, text, pos, amt)
 The new text replaces amt characters, beginning at pos in the given note or
 button. An amt of -1 means `to the end of text'.

cleartext
 CLEARTEXT (arg)
 Remove all the text from the given note or button.

deletetext
 oldtext = DELETETEXT (note, pos, amt)
 Delete amt characters beginning at pos in the given note or button, and
 return the deleted text. An amt of -1 means `to the end of text'.

Items and lists
getitemcolor
 color = GETITEMCOLOR (item)
 Return the color of the given item.

setitemcolor
 old = SETITEMCOLOR (item, color)
 Set the color of the given item, and return its previous color.

getitemtext
 text = GETITEMTEXT (item)
 Return the text string associated with the given item.

setitemtext
 oldtext = SETITEMTEXT (item, text)
 Set the item text to text, and return the former text.

insertitem
 item = INSERTITEM (next, text, color)
 Create a new item with the given color and text, inserted before item next
 in its list, and return the objnum of the new item.

appenditem
 item = APPENDITEM (list, text, color)
 Create a new item with the given color and text, append it to the given
 list, and return its objnum.

moveitem
 item = MOVEITEM (olditem, pos)
 Move the given item within its list to position pos, and return its new
 objnum.

clearlist
 CLEARLIST (list)
 Empty the given list of all items.

sortlist
 SORTLIST (list1 [,list2, ..., listn])
 Sort the items in the given list in ascending lexical order. If more than
 one list is given, the first is sorted, and the others are re-ordered in the
 same way as list1. All the lists must have the same number of items.

refreshlist
 REFRESHLIST (list)
 Redraw the given list. Use this to force a refresh while the INTERACTIVE
 flag is turned off (which normally suppresses list rendering).

listscroll
 LISTSCROLL (item)
 Scroll the given item's list so that the item is at the top, or as near as
 possible to the top, of the list's display area.

listheight
 count = LISTHEIGHT (list)
 Return the number of items the given list can display at its current size.
 The list does not necessarily contain this many items.

Searches
searchstart
 SEARCHSTART (start)
 Set the default starting point for SEARCHNAME, SEARCHPAGENAME and
 SEARCHTEXT. If start is an objnum, set the starting point to the
 corresponding page and object (if the objnum is that of a page or the bin,
 the object is taken to be the first in the relevant object list). An empty
 start string is equivalent to specifying '1:' - the first page.

searchname
 obj = SEARCHNAME (start, substr)
 From the given starting point in the hyperbook, search for an object whose
 name contains substr, and return its objnum (the empty string if not found).
 If the start argument is empty, the search begins where the most recent
 search left off, or at the point set by SEARCHSTART. The search is case
 insensitive.

searchpagename
 obj = SEARCHPAGENAME (start, substr)
 From the given starting point in the hyperbook, search for a page whose name
 contains substr, and return its objnum (the empty string if not found). If
 the start argument is the empty string, the search begins where the most
 recent search left off, or at the point set by SEARCHSTART. The search is
 case insensitive.

searchtext
 obj = SEARCHTEXT (start, substr)
 From the given starting point in the hyperbook, search for an object or list
 whose text contains substr, and return its objnum (the empty string if not
 found). If start is the empty string, the search begins where the most
 recent search left off, or as set by SEARCHSTART. The search is case
 insensitive.

searchitems
 item = SEARCHITEMS (arg, text)
 Search a list (from the beginning, if arg is a list; or from the given item)
 for text, and return either the objnum of the item containing the text or,
 if the search failed, the empty string. The search is case insensitive.

searchnote
 pos = SEARCHNOTE (arg, pattern, start)
 Search the given note or button, arg, starting at position start, for the
 string pattern, and return the position at which it is found, or -1 if the
 search fails. The search is case insensitive.

User input
getresponse
 bool (1 or 0) = GETRESPONSE (prompt)
 Put up the Okay/Cancel requester with the given prompt string. Return 1 if
 the user clicks Okay (the checkmark), 0 for Cancel (the X).

inputstring
 str = INPUTSTRING (prompt, default)
 Prompt the user to enter a string (modifying the given text, if default is
 non-empty) and return it. Note: the empty string is returned if the user
 cancels the requester.

inputform
 text = INPUTFORM (prompt, formtext)
 Obtain multiple lines of input from the user. Formtext specifies the label
 and the default string for each input line in this format:
    <label>:<text>[<LF><label>:<text> ...]
 where LF is a linefeed (in ARexx, a linefeed is '0a'X). The returned text
 consists of the input strings separated by LFs.

inputobject
 obj = INPUTOBJECT (prompt)
 Prompt the user to select an object from a list of those on the current
 page. Return the objnum of the selected object.

inputpage
 page = INPUTPAGE (prompt)
 Prompt the user to select a page from the page list. Return the objnum of
 the selected page.

selectitem
 item = SELECTITEM (list, prompt)
 Display the given prompt to the user, and wait for a click on an item in the
 given list. Return the objnum of the selected item.

getclickrow
 row = GETCLICKROW (prompt)
 Display the given prompt in a bar at the top the screen. When the user
 clicks on the page, return the number of the scan-line clicked on.

getcolumn
 col = GETCOLUMN ()
 Return the column that was clicked on the last time GETCLICKROW was called.

getobjectat
 obj = GETOBJECTAT (x, y)
 Return the objnum of the object at page co-ordinates (x,y). A null objnum
 (the empty string) is returned if there is no object at the given
 co-ordinates.

beginprompt
 BEGINPROMPT (text)
 Open the prompt window along the top of the screen, containing the given
 text. If not closed with ENDPROMPT, the window will close automatically when
 the script finishes executing.

endprompt
 ENDPROMPT ()
 Close the prompt window (opened with BEGINPROMPT).

filerequest
 file = FILEREQUEST (prompt, default)
 Open a file requester with the given prompt and default AmigaDOS path name,
 and return the path name selected by the user. Return the empty string if
 the user cancels.

Text editing
loadtext
 text = LOADTEXT (filename)
 Return a string whose value is the entire contents of the given file.

savetext
 SAVETEXT (file, text)
 Create a file whose contents is the given text.

savemoretext
 SAVEMORETEXT (file, text)
 Append the given text to an existing file.

edittext
 newtext = EDITTEXT (name, text)
 Make the text available for editing in the built-in text editor, displaying
 the given name in the editor's title bar. Return the edited text.

Printing
getprintwidth
 width = GETPRINTWIDTH ()
 Return the printer line width as set in Preferences, calculated as: right
 margin - left margin + 1.

formattext
 newtext = FORMATTEXT (text, margin, width)
 Create and return a new string in which the given string has been
 word-wrapped to lines of width characters, with margin extra spaces added to
 the beginning of each line (these are not counted as part of width).

printpage
 bool (1 or 0) = PRINTPAGE ()
 Print the current page... this is just like selecting Print Page on the
 Project menu. Return 1 if the print succeeded, otherwise 0.

Data display
showpic
 bool = SHOWPIC (file)
 Display the given ILBM file. Return FALSE (0) if the file does not exist.

showtext
 bool = SHOWTEXT (file)
 Display the given text file. Return FALSE (0) if the file does not exist.

showtextrange
 bool (1 or 0) = SHOWTEXTRANGE (file, start, amt)
 Display a text range from the given file, beginning start bytes into the
 file and continuing for amt bytes. (The equivalent line number values for
 start and amt can be converted to byte values with the `textrange'
 utility.)

Language support
numelements
 num = NUMELEMENTS (arg)
 Return the number of elements in a page, the bin, a group or a list. A group
 is counted as one element, regardless of how many objects it contains.

sequencenumber
 num = SEQUENCENUMBER (arg)
 Return the list position of a page, object or item, counting from 1. For
 objects within a group, the position returned is relative to the group, not
 the containing page.

totalelements
 num = TOTALELEMENTS (arg)
 Return the number of elements contained in a page, the bin, a list object or
 a group at all levels (i.e. including nested groups). This is equivalent to
 NUMELEMENTS only for lists.

gettype
 type = GETTYPE (arg)
 Return one of these strings: Page, Bin, Drawing, Picture, Note, List,
 Button, Group, Item, depending on the type of the argument.

getpage
 pg = GETPAGE (arg)
 Return the objnum of the page to which arg pertains.

getnext
 next = GETNEXT (arg)
 If arg is a page or an item, the returned value next is the objnum of the
 next page or item. If arg is an object, next is the objnum of the next
 object in a depth-first search of the page, or the first object on the next
 page if there are no more objects on the current page. An empty objnum is
 returned if the end of the list in arg's category has been reached.

getnextsib
 next = GETNEXTSIB (arg)
 If arg is a page or an item, the returned value next is the objnum of the
 next page or item. If arg is an object, next is the objnum of the next
 object at the same level as the given one (i.e. without descending if arg is
 a group), or the empty string if there are no more objects in arg's list.

objectnumber
 obj = OBJECTNUMBER (arg, num)
 Return the objnum of the object/item whose sequence number on the given
 (page or group)/list is num. The empty string is returned if the sequence
 number is invalid. If arg is the empty string, return the objnum of page
 num.

parent
 parent = PARENT (arg)
 Return the objnum of the page, bin, group or list one level up from the
 given object or item.

currentpage
 page = CURRENTPAGE ()
 Return the objnum of the current page.

initiator
 obj = INITIATOR ()
 Return the objnum of the object or item that launched the current macro or
 ARexx command. Return the empty string if the macro or command was not
 launched by an object or item (e.g. from a menu).

ismacro
 bool (1 or 0) = ISMACRO (name)
 Return 1 if the given name is that of a macro in the current hyperbook, and
 0 otherwise. (A zero result does not preclude the possibility that the macro
 may be available to be executed from disk.)

movemacro
 MOVEMACRO (macroname, newpos)
 Move the named macro to position newpos in the macro list, which is
 displayed by several selections in the ARexx menu. If the given position is
 less than or equal to zero, the macro is moved to the end of the list.

interactive
 oldstate = INTERACTIVE (bool)
 Set (1) or clear (0) interactive mode, and return its previous state. In
 interactive mode, objects are updated on-screen after each operation.
 Otherwise, objects are updated only: when REFRESHLIST or REFRESHPAGE is
 used; on re-entering interactive mode explicitly (with the present
 function); on exiting a command or macro to interactive operation. Commands
 and macros always start in interactive mode.

pause
 PAUSE (tenths)
 Pause program execution for the given number of tenths of seconds.

inform
 INFORM (string)
 Display the given string, and wait for the user to click Okay.

rand
 value = RAND (low, high)
 Return a pseudo-random integer between low and high, inclusive. Unlike
 ARexx's RANDOM function, RAND does not need to be reseeded for each script.